显示 Kanzi Studio 中的 Kanzi Engine 插件自定义类型的参考

您可以使用 Kanzi Engine 插件通过 Kanzi Engine API 创建自定义类型和消息,并在 Kanzi Studio 中使用它们。

要向 Kanzi Studio 传递有关您在 Kanzi Engine 插件中创建的自定义属性类型和消息的信息,应声明描述这些属性类型和消息的元数据。元数据使 Kanzi Engine 插件用户可以与 Kanzi Studio 中的插件内容交互。例如,元数据定义用于设置属性值的 Kanzi Studio 属性编辑器的类型,以及可供选择的值集。

仅声明您需要的元数据。Kanzi Studio 会将默认值分配给您没有设置的特性。

此表列出了您可以使用的元数据特性。

特性 (Attribute) 描述 (Description) 用于属性类型 用于消息类型
displayName Kanzi Studio 中显示的属性或消息名称 x x
tooltip 属性或消息的工具提示 x x
类别 属性、触发器或动作类别按其在 Kanzi Studio 中显示的方式命名 x x
valueProvider Kanzi Studio 让用户选择的属性的可能值的来源 x  
host Kanzi Studio 推荐给属性的节点类型,以及是由 Kanzi Studio 自动添加该属性,还是让用户添加该属性 x  
editor Kanzi Studio 编辑器用于设置属性值的类型 x  
DefaultValue 属性的默认值 x  
LowerBound 属性可以拥有的最低值 x  
UpperBound 属性可以拥有的最高值 x  
步进 Kanzi Studio 用户编辑属性值时的更改量 x  
Sendable Kanzi Studio 是否将消息显示为动作   x
Listenable Kanzi Studio 是否将消息显示为触发器   x
SortingIndex Kanzi Studio 中其属性类别中属性的位置 x  
studioVisibility Kanzi Studio 中是否提供属性或消息 x x
LegacyName Name of the property or message in the earlier versions of the plugin x x

displayName

设置 Kanzi Studio 中显示的属性或消息的名称。

语法 metadata.displayName = "name";
name 您希望在 Kanzi Studio 中显示属性或消息名称的方式
示例
metadata.displayName = "Video Filename";

tooltip

设置属性或消息的工具提示。如果用户在编写脚本或应用程序代码时需要该属性或消息的 Kanzi Engine 名称,Kanzi Studio 会附加工具提示文本。

语法 metadata.tooltip = "text";
text 工具提示文本
示例
metadata.tooltip = "Name of the video file to be played";

类别

设置 Kanzi Studio 属性 (Properties) 中显示属性的类别名称的方式。Kanzi Studio 始终首先列出 常规 (General)描述 (Description) 属性类别,然后以首字母顺序列出其他属性类别。

语法 metadata.category = "text";
text 类别 (Category)
示例
metadata.category = "Video";

valueProvider

设置 Kanzi Studio 如何获取可供用户选择的属性的可能值。

语法 metadata.valueProvider = "key:value";
key
  • ProjectObject 提供通过 value 设置的特定类型的节点或资源。
  • PropertyType 会在下拉菜单中列出所有可用的属性类型。请不要设置 value
    请不要设置编辑器类型。Kanzi Studio自动设置正确的 editor
    使用带有字符串属性类型的 PropertyType
  • StringList 会提供用户可添加项的列表。请不要设置 value
    请不要设置编辑器类型。Kanzi Studio自动设置正确的 editor
    使用带有字符串属性类型的 StringList
  • Enum 会提供通过 value 设置的选项下拉菜单,它会列出项(字符串)以及 Kanzi 映射这些项的值(整数值)。
    使用具有 int 和 enum 属性类型的 Enum
    使用管道符号分隔项和值,用分号分隔项-值配对列表:
    Enum:string1|int1;string2|int2;...;stringN|intN
示例
//将值提供者设为 3D 节点。
//(Kanzi Studio 默认使用 Node 3D dropdown editor。)
metadata.valueProvider = "ProjectObject:Node3D";
//提供包含所有可用属性类型的下拉菜单。
//(请不要设置编辑器类型。Kanzi Studio 会自动设置正确的 editor。)
metadata.valueProvider = "PropertyType";
//提供用户可添加项的列表。
//(请不要设置编辑器类型。Kanzi Studio 会自动设置正确的 editor。)
metadata.valueProvider = "StringList";
//提供 Kanzi 映射到整数 0 到 5 的不同维度间的方向列表。
metadata.valueProvider = "Enum : Left to Right|0;Right to Left|1;Top to Bottom|2;Bottom to Top|3;Near to Far|4;Far to Near|5";
//创建一个引用节点的字符串。
PropertyType<string> MyPlugin::NodeRefByStringProperty(kzMakeFixedString("MyPlugin.NodeRefByString"), "", 0, false,
                                                       KZ_DECLARE_EDITOR_METADATA
                                                       (
                                                           metadata.displayName = "Node Reference by String";
                                                           // 您将 valueProvider 设为 ProjectObject:Node3D 时,
                                                           // Kanzi Studio 会自动使用 Node 3D 选择器编辑器。
                                                           metadata.valueProvider = "ProjectObject:Node3D";
                                                       ));
//创建引用预设件资源的字符串。
PropertyType<string> MyPlugin::PrefabRefByStringProperty(kzMakeFixedString("MyPlugin.PrefabRefByString"), "", 0, false,
                                                         KZ_DECLARE_EDITOR_METADATA
                                                         (
                                                             metadata.displayName = "Prefab Reference by String";
                                                             // 您将 valueProvider 设为 ProjectObject:PrefabTemplate 时,
                                                             // Kanzi Studio 会自动使用 Prefab 模板选择器编辑器。			
                                                             metadata.valueProvider = "ProjectObject:PrefabTemplate";
                                                         ));
//创建引用预设件资源的共享指针。
PropertyType<ResourceSharedPtr> MyPlugin::PrefabRefBySharedPtrProperty(kzMakeFixedString("MyPlugin.PrefabRefBySharedPtr"), ResourceSharedPtr(), 0, false,
                                                                       KZ_DECLARE_EDITOR_METADATA
                                                                       (
                                                                           metadata.displayName = "Prefab Reference by Shared Pointer";
                                                                           //您将 valueProvider 设为 ProjectObject:PrefabTemplate 时,
                                                                           // Kanzi Studio 会自动使用 Prefab 模板选择器编辑器。		
                                                                           metadata.valueProvider = "ProjectObject:PrefabTemplate";
                                                                       ));
//创建引用材质资源的共享指针。
PropertyType<ResourceSharedPtr> MyPlugin::MaterialRefBySharedPtrProperty(kzMakeFixedString("MyPlugin.MaterialRefBySharedPtr"), ResourceSharedPtr(), 0, false,
                                                                 KZ_DECLARE_EDITOR_METADATA
                                                                 (
                                                                     metadata.displayName = "Material Reference by Shared Pointer";
                                                                     //您将 valueProvider 设为 ProjectObject:Material 时,
                                                                     // Kanzi Studio 会自动使用 Material 下拉编辑器。
                                                                     metadata.valueProvider = "ProjectObject:Material";
                                                                 ));

host

设置 Kanzi Studio 推荐给属性的节点类型,以及是由 Kanzi Studio 自动添加该属性,还是让用户添加该属性。

如果没有设置 host 特性,Kanzi Studio 会将该属性作为常用属性,添加到您为其创建了该属性类型的节点,并让用户将该属性添加到任何其他类型的节点。

语法 metadata.host = "nodeType:addition";
nodeType 您想要 Kanzi Studio 为其提供该属性的节点类型。
addition Kanzi Studio 如何添加属性或让用户添加该属性:
  • user 会让用户通过上下文菜单或 添加属性 (Add Properties) 窗口添加该属性。
  • context 会让用户采用和 user 相同的方式添加该属性,也可通过添加属性 (Add Properties) 窗口的上下文选项卡。
  • freq 会将该属性添加为常用属性,在属性 (Properties) 中带有 标记。用户还可以采用和 context 相同的方式添加该属性。
  • auto 会自动添加该属性。
  • fixed 会自动添加该属性,并且不让用户移除该属性。
您可以设置用逗号分隔多个 nodeType:addition 对。
示例
//将该属性添加为所有 2D 节点的常用属性。
metadata.host = "Node2D:freq";
//为所有 VideoView2D 节点自动添加该属性,并让用户添加图像 (Image) 节点的属性。
metadata.host = "VideoView2D:auto,Image2D:user";

editor

设置 Kanzi Studio 用户用于设置属性值的编辑器类型。如果您没有设置编辑器,Kanzi 会分配一个默认编辑器。

如果您将 valueProvider 特性设置为 PropertyTypeStringList,请不要设置编辑器类型。Kanzi Studio 自动分配正确的编辑器。

如需 Kanzi Studio 属性编辑器的列表,请参阅 Kanzi Engine 插件中声明的属性类型的 Kanzi Studio 属性编辑器

语法 metadata.editor = "editor";
editor Kanzi Studio 属性编辑器名称。请参阅 Kanzi Engine 插件中声明的属性类型的 Kanzi Studio 属性编辑器
示例
//将编辑器设为 BrowseFileTextEditor,该编辑器含有一个文本框,旁边有一个浏览 (Browse) 按钮。
metadata.editor = "BrowseFileTextEditor";

DefaultValue

设置 Kanzi Studio 中显示属性或消息默认值的方式。

语法 metadata["DefaultValue"] = "value";
value Kanzi Studio 中的属性或消息的默认值
示例
//将 Kanzi Studio 中的字符串属性的默认值设为 video.mp4。
metadata["DefaultValue"] = "video.mp4";
//将 Kanzi Studio 中的浮点属性的默认值设为 180。
metadata["DefaultValue"] = "180";

LowerBound

设置属性在 Kanzi Studio 中的最低值。通过整数和浮点属性类型使用 LowerBound。另请参阅 UpperBound步进

语法 metadata["LowerBound"] = "value";
value 属性的最低值
示例
//将属性的最低值设为 0。
metadata["LowerBound"] = "0";

UpperBound

设置属性在 Kanzi Studio 中的最高值。通过整数和浮点属性类型使用 UpperBound。另请参阅 LowerBound步进

语法 metadata["UpperBound"] = "value";
value 属性的最高值
示例
//将属性的最高值设为 360。
metadata["UpperBound"] = "360";

步进

设置当 Kanzi Studio 用户编辑属性值时的更改量。通过整数和浮点属性类型使用 Step。另请参阅 LowerBoundUpperBound

语法 metadata["Step"] = "value";
value 设置当 Kanzi Studio 用户编辑属性值时的更改量
示例
//将 Kanzi Studio 用户编辑属性值时的更改量设为 10。
metadata["Step"] = "10";

Sendable

设置Kanzi Studio 是否在触发器动作下拉菜单中将消息显示为动作。

语法 metadata["Sendable"] = "value"
True 将消息显示为动作。默认值。
False 不将消息显示为动作。
示例
//不将消息显示为动作。
metadata["Sendable"] = "False";

Listenable

设置 Kanzi Studio 是否在添加触发器 (Add Triggers) 窗口和添加触发器 (Add Trigger) 上下文菜单中将消息显示为触发器。

语法 metadata["Listenable"] = "value"
True 将消息显示为触发器。默认值。
False 不将消息显示为触发器。
示例
//不将消息显示为触发器。
metadata["Listenable"] = "False";

SortingIndex

设置在 Kanzi Studio 属性 (Properties) 窗口中显示的属性类别中的位置。默认情况下,Kanzi Studio 根据属性类型在元类定义中的顺序,确定它们在某一属性类别中的排序。请参阅类别

语法 metadata["SortingIndex"] = "index"
index 该属性在 Kanzi Studio 中显示的属性类别中的位置。
示例
//在该属性的属性类别中,将其作为第一个属性显示。
metadata["SortingIndex"] = "1";

studioVisibility

设置 Kanzi Studio 中是否提供属性或消息。

语法 metadata["StudioVisibility"] = "value"
Visible Kanzi Studio 中显示属性或消息。默认值。
UserHidden Kanzi Studio 用户隐藏属性或消息,但保持 Kanzi Studio 对该属性或消息可用。
Hidden Kanzi Studio 不知道属性或消息,kzb 文件中不包括属性或消息。
您可以为实现插件内部功能的属性和消息使用此值,无需在 Kanzi Studio 中设置。
示例
//让 Kanzi Studio 不知道属性。
metadata["StudioVisibility"] = "Hidden";

LegacyName

Sets the name of the property type or message in earlier versions of the Kanzi Engine plugin.

When you rename a property type or message, use LegacyName to inform Kanzi Studio about the change. When a Kanzi Studio user updates the Kanzi Engine plugin in a Kanzi Studio project, Kanzi Studio renames all instances of the property type or message in that project.

Syntax metadata["LegacyName"] = "name"
Values
name Name of the property type or message in earlier versions of the plugin. Separate legacy names with semicolons.
Examples
// Give Kanzi Studio the name of the property type or message in the earlier versions of the plugin.
metadata["LegacyName"] = "MyOldPropertyName";

另请参阅

Kanzi Engine 插件

使用 Kanzi Engine 插件

创建 Kanzi Engine 插件

Kanzi Engine 插件中声明的属性类型的 Kanzi Studio 属性编辑器

教程:从数据源获取应用程序数据

Node2D 插件示例

Node3D 插件示例